WIP - exploring what is possible, still needs cleanup

Summary

Adds a new @bomb.sh/tab/install subpath that ships built-in installer and uninstaller utilities for shell completions. CLI authors can wire it into an init flow, a complete install subcommand, or a postinstall hook — no more asking users to copy-paste source <(my-cli complete zsh) into their shellrc.

Closes #117.

import { installShellCompletions, uninstallShellCompletions } from '@bomb.sh/tab/install';

await installShellCompletions({ name: 'my-cli', shell: 'auto' });
await uninstallShellCompletions({ name: 'my-cli' });

Design

The installer is opt-in, idempotent, and never touches .zshrc / .bashrc on its own. Files we write start with a # tab-completion managed-by=tab name=… version=… marker so re-runs detect existing managed installs (and uninstall refuses to clobber unmanaged files). PowerShell uses sentinel-wrapped blocks (# >>> tab:my-cli >>> / # <<< tab:my-cli <<<) for idempotent profile editing.

The function returns a structured InstallResult with one of:

• installed / already-installed / updated — done
• needs-user-action — we did our part, returns concrete next-step instructions (e.g. add compinit line, install bash-completion@2)
• blocked — refused to proceed (CLI not on PATH, unmanaged file conflict)
• failed — unexpected error

Pre-flight checks before any shell-specific logic:

• Shell detection — \$PSModulePath (Windows) → ppid → /proc/<ppid>/comm (Linux) or ps -p (macOS) → \$SHELL fallback
• PATH reachability — strips node_modules/.bin segments from PATH before resolving, so it correctly rejects local node_modules shims while still accepting fnm/nvm/asdf-managed binaries
• Conflict scan — refuses to overwrite a completion file without our marker unless force: true

The uninstaller for zsh walks every dir we might have written to (current \$fpath + Homebrew + ~/.zsh/completions) so it cleans up even if the user's env has changed since install.

Notes on what this is not

Other CLIs in this space (kubectl, gh, AWS CLI) print scripts to stdout and never auto-install. Only Bun auto-installs, and it silently fails on errors. This implementation takes a third path: auto-install where the environment supports it without shellrc edits (fish always, brew-zsh, Linux bash), return clear remediation when it doesn't.

Test plan

• Typecheck clean (`pnpm type-check`)
• Build emits `dist/install.mjs` + `.d.mts` (`pnpm build`)
• Full suite passes — 20 new tests in `tests/install.test.ts` covering markers, sentinel upsert/remove, fish install/uninstall (managed, already-installed, updated, blocked, force, dryRun), bash install/uninstall happy path. 207 passed total, no regressions.
• Manual smoke test on macOS zsh: blocked path returns clear remediation when CLI is not on PATH; happy path detects fpath + compinit and reports `installed` with one next-step instruction
• Manual smoke test on Linux bash (would appreciate help testing this on a Linux machine before merge)
• Manual smoke test on Windows PowerShell

Files

`src/install/`:

• `types.ts` — `InstallOptions`, `InstallResult`, `UninstallOptions`, `UninstallResult`
• `detect.ts` — shell, name (argv/package.json), PATH, install method, zsh fpath, bash-completion presence, PowerShell profile + execution policy
• `markers.ts` — file marker, sentinel block helpers (`wrapBlock` / `upsertBlock` / `removeBlock`)
• `fish.ts`, `zsh.ts`, `bash.ts`, `powershell.ts` — per-shell install + uninstall
• `context.ts`, `print.ts`, `index.ts` — wiring + the main exports

Build config (`tsdown.config.ts`) and `package.json` exports map are updated for the new `./install` subpath.

🤖 Generated with Claude Code